home *** CD-ROM | disk | FTP | other *** search
/ Aminet 6 / Aminet 6 - June 1995.iso / Aminet / misc / sci / xmgr_docs.lha / xmgr_docs / xmgr.man.txt < prev    next >
Encoding:
Text File  |  1995-01-30  |  15.5 KB  |  402 lines
  1. ACE/gr(1)                                               ACE/gr(1)
  2.  
  3. NAME
  4.        ACE/gr - graphics for exploratory data analysis
  5.  
  6. SYNOPSIS
  7.        xvgr  (XView)  or  xmgr  (Motif) [ -autoscale x|y|xy ] [ [
  8.        -noauto x|y|xy ] [ -arrange rows columns ] [ -cols columns
  9.        ]  [  -rows  rows  ]  [  -device  device_number ] [ -batch
  10.        batch_file ] [ -noask ] [  -eps  ]  [  -pipe  ]  [  -graph
  11.        graph_number  ]  [  -maxplot  number_of_sets ] [ -maxgraph
  12.        number_of_graphs  ]  [  -graphsets  number_of_sets   ]   [
  13.        -graphtype  graph_type  ]  [  -log  x|y|xy  ] [ -printfile
  14.        graphics_output_file ] [ -type XY_data_set_type ]  [  -ihl
  15.        IHL_formatted_file  ] [ -nxy ] [ -xy ] [ -xydx ] [ -xydy ]
  16.        [ -xydxdx ] [ -xydydy ] [ -xydxdy ] [ -xyz ] [  -xyd  ]  [
  17.        -xyr ] [ -hilo ] [ -block block_data ] [ -parameter param-
  18.        eter_file  ]  [  -pexec  parameter_string  ]  [   -results
  19.        result_file  ]  [  -rvideo  ] [ -mono ] [ -world xmin ymin
  20.        xmax ymax ] [ -view  xmin  ymin  xmax  ymax  ]  [  -source
  21.        data_source  ]  [ -GXinvert ] [ -GXxor ] [ -maxcolors num-
  22.        ber_of_colors ] [ -bc ] [ -bs ] [ -nobs ] [ -dc ] [  -nodc
  23.        ]  [  -redraw ] [ -noredraw ] [ -refresh refresh_value ] [
  24.        -debug debug_level ] [ data_files ]
  25.  
  26. DESCRIPTION
  27.        ACE/gr is a data/function plotting tool  for  workstations
  28.        or X-terminals using X.  A few of its features are:
  29.  
  30.        +o      Polynomial  regression,  splines, running averages,
  31.               DFT/FFT, cross/auto-correlation.
  32.  
  33.        +o      Plots up to 10 graphs with 30 datasets per graph.
  34.  
  35.        +o      User-defined scaling, tick marks, labels,  symbols,
  36.               line styles, colors.
  37.  
  38.        +o      Batch mode for unattended plotting.
  39.  
  40.        +o      Read and write parameters used during a session.
  41.  
  42.        +o      Support  through device independent graphic drivers
  43.               for PostScript, and FrameMaker .mif format.
  44.  
  45. OVERVIEW
  46.        While ACE/gr has a convenient  point-and-click  interface,
  47.        most  parameter  settings  and  operations  are  available
  48.        through   a   command    line    interface    (found    in
  49.        Files/Commands).  See the ACE/gr User's Manual for further
  50.        information. The following discusses command line  parame-
  51.        ters,  data  file  formats,  hot keys, examples, and a few
  52.        bugs. See the ACE/gr User's Manual for a complete descrip-
  53.        tion of ACE/gr and its capabilities.
  54.  
  55.                             April 1992                          1
  56.  
  57. ACE/gr(1)                                               ACE/gr(1)
  58.  
  59. OPTIONS
  60.        -autoscale [x|y|xy]
  61.               Autoscale  the  axis  denoted by "x" or "y" or both
  62.               axes by "xy" overiding any parameter file specified
  63.               by the -p or -parameter option.
  64.  
  65.        -noauto [x|y|xy]
  66.               Suppress  autoscaling   the  axis denoted by "x" or
  67.               "y" or both axes by "xy." Use -noauto if  the  data
  68.               has  imbedded parameter settings that set the world
  69.               and tick spacing.
  70.  
  71.        -arrange [rows columns]
  72.               Arrange graphs in column major order starting  from
  73.               the  lower  left  corner in a grid rows by columns.
  74.               For example, '-arrange 2 2' will position the first
  75.               four  graphs (0, 1, 2, 3) in a 2x2 matrix of graphs
  76.               starting with graph 0 in the lower left  corner  of
  77.               the plotting surface.
  78.  
  79.        -rows [rows]
  80.               Arrange the first 'rows' graphs in 'rows' rows.
  81.  
  82.        -cols [cols]
  83.               Arrange  the first 'cols' graphs in 'cols' columns.
  84.  
  85.        -batch [batch_file]
  86.               Execute the commands in batch_file on startup.
  87.  
  88.        -noask Force the dialog or prompt requesting that files be
  89.               overwritten  to  always  return TRUE (meaning that,
  90.               yes, files will be overwritten without asking, even
  91.               if  they  exist).  This supresses the yes/no dialog
  92.               for the entire ACE/gr session.
  93.  
  94.        -device [device_number]
  95.               Set the hardcopy device to device.
  96.  
  97.               The device numbering follows:
  98.  
  99.                   1 .. PostScript landscape
  100.                   2 .. PostScript portrait
  101.                   3 .. FrameMaker .mif landscape
  102.                   4 .. FrameMaker .mif portrait
  103.                   5 .. HPGL landscape
  104.                   6 .. HPGL portrait
  105.  
  106.        -printfile [graphics_output_file]
  107.               Write  the   graphics   output   to   file   graph-
  108.               ics_output_file  rather than spool graphics data to
  109.               a printer.
  110.  
  111.        -eps   Set the PostScript driver to write EPS.
  112.  
  113.                             April 1992                          2
  114.  
  115. ACE/gr(1)                                               ACE/gr(1)
  116.  
  117.        -ihl [file_name]
  118.               Assume file_name or the next source of data  is  in
  119.               IHL format (a local format)
  120.  
  121.        -log [x|y|xy]
  122.               Set the current graph type to logarithmic depending
  123.               the the string "x" or "y" or both axes by "xy".
  124.  
  125.        -nxy   The format of the next data source is X1,  Y1,  Y2,
  126.               ..., Yn.
  127.  
  128.        -block [block_data]
  129.               The file block_data is a block data file.
  130.  
  131.        -type [data_set_type]
  132.               The   format   of   the   next   data   source   is
  133.               data_set_type.  Where data_set_type is one of  xydx
  134.               (XY  data  with  error bars along X), xydy (XY data
  135.               with error bars along  Y),  xydxdx  (XY  data  with
  136.               error bars along X of differing values), xydydy (XY
  137.               data with error bars along Y of differing  values),
  138.               and
  139.  
  140.        -param [parm_file]
  141.               Read the parameter file parm_file.
  142.  
  143.        -pexec [parameter_setting]
  144.               Interpret parameter_setting as a parameter setting.
  145.  
  146.        -graph [graph_number]
  147.               Make graph_number the current graph.   Graph_number
  148.               is  an integer between 0 and MAXGRAPH (usually 10).
  149.  
  150.        -graphtype [graph_type]
  151.               Set the current graph type  to  graph_type.   Where
  152.               graph_type is one of xy, logx, logy, logxy, or bar.
  153.  
  154.        -rvideo
  155.               Exchange the color indices for black and white.
  156.  
  157.        -mono  Ignore the number of available colors and use black
  158.               and white on the display only.
  159.  
  160.        -GXinvert
  161.               Set  the  write mode to INVERT for rubberband lines
  162.               and focus markers.
  163.  
  164.        -GXxor Set the write mode to XOR for rubberband lines  and
  165.               focus markers.
  166.  
  167.        -dc    Allow  double  click operations overriding resource
  168.               settings.
  169.  
  170.        -nodc  Disallow   double   click   operations   overriding
  171.  
  172.                             April 1992                          3
  173.  
  174. ACE/gr(1)                                               ACE/gr(1)
  175.  
  176.               resource settings.
  177.  
  178.        -redraw
  179.               Allow  redraw  for  refreshing  the canvas when the
  180.               display does not do backing store.
  181.  
  182.        -noredraw
  183.               Do not do a redraw for refreshing the  canvas  when
  184.               the display does not do backing store.
  185.  
  186.        -maxplot [number_of_sets]
  187.               Set the number of sets for each graph.
  188.  
  189.        -maxgraph [number_of_graphs]
  190.               Set the number of graphs for the current session.
  191.  
  192.        -source [disk|pipe|source]
  193.               Set  source  for  the  next data file, the argument
  194.               takes on the following values:
  195.  
  196.                  disk - Data file is on disk.
  197.                  pipe - Read from a pipe.
  198.                  stdin - ACE/gr is in a pipe, read from  standard
  199.               input.
  200.  
  201.                  The  setting selected here stays in effect until
  202.               the next use of the -source command line option  is
  203.               given.   This  differs  from  earlier  versions  of
  204.               ACE/gr.
  205.  
  206.        -world [xmin ymin xmax ymax]
  207.               Set the user coordinate system of the current graph
  208.               to a rectangle described by (xmin, ymin) and (xmax,
  209.               ymax).
  210.  
  211.        -view [xmin ymin xmax ymax]
  212.               Set the viewport of the current graph to a  rectan-
  213.               gle described by (xmin, ymin) and (xmax, ymax).
  214.  
  215.        -legend load
  216.               When all sets have been read, copy the set comments
  217.               (usually the file name from which the set was read)
  218.               to the set legend labels and turn the legend on.
  219.  
  220.        -usage Display  a  brief  explanation of command line set-
  221.               tings
  222.  
  223.        On     startup,     ACE/gr     will     look     for     a
  224.        .xmgrrc (XView) or .xmgrrc (Motif) file in the users' home
  225.        directory allowing the user to change the default behavior
  226.        of      ACE/gr.      The      construction      of     the
  227.        .xmgrrc (XView) or .xmgrrc (Motif) file is the same as for
  228.        a parameter file.
  229.  
  230.                             April 1992                          4
  231.  
  232. ACE/gr(1)                                               ACE/gr(1)
  233.  
  234. REFERENCE
  235.        Note:  all  data  are  assumed  to be delimited by tabs or
  236.        blanks.
  237.  
  238.        XY data sets:
  239.  
  240.           xy     ...   Multiple xy data sets composed of X and  Y
  241.        one  point  per  line,  data sets separated by '&' or some
  242.        other non-digit character (except '#' and '@', see below).
  243.  
  244.           nxy      ...    Multiple xy data sets composed of X and
  245.        Y1 Y2 Y3 Y4 ... Y30. These data files may be  concatenated
  246.        as with the 'xy' format.
  247.  
  248.           xydx    ...    Multiple xy data sets composed of X Y DX
  249.        one point per line,  data sets separated by  '&'  or  some
  250.        other  non-digit  character.  DX is the value that will be
  251.        printed as an error relative to X, i.e., the point will be
  252.        plotted with an error bar at (x+-dx, y).
  253.  
  254.           xydy    ...    Multiple xy data sets composed of X Y DY
  255.        one point per line,  data sets separated by  '&'  or  some
  256.        other  non-digit  character.  DY is the value that will be
  257.        printed as an error relative to Y, i.e., the point will be
  258.        plotted with an error bar at (x, y+-dy). This is the usual
  259.        file type for error bars.
  260.  
  261.           xydxdx ...   Multiple xy data sets composed of X Y  DX1
  262.        DX2  one  point  per  line,  data sets separated by '&' or
  263.        some other non-digit character. DX1 and DX2 are the values
  264.        of  the  error  bars to be draw to the right and left of X
  265.        respectively (assuming DX1 and DX2  are  positive),  i.e.,
  266.        the  point  will  be plotted with error bars at (x+dx1, y)
  267.        and (x-dx2, y).
  268.  
  269.           xydydy ...   Multiple xy data sets composed of X Y  DY1
  270.        DY2  one  point  per  line,  data sets separated by '&' or
  271.        some other non-digit character. DY1 and DY2 are the values
  272.        of  the error bars to be draw to the on the top and bottom
  273.        of Y respectively (assuming DY1  and  DY2  are  positive),
  274.        i.e.,  the  point  will  be plotted with error bars at (x,
  275.        y+dy1) and (x, y-dy2).
  276.  
  277.           xydxdy ...   Multiple xy data sets composed of X  Y  DX
  278.        DY one point per line,  data sets separated by '&' or some
  279.        other non-digit character. DX and DY are the values of the
  280.        error  bars  to  be draw to the left and right of X and on
  281.        the top and bottom of Y respectively (assuming DX  and  DY
  282.        are  positive), i.e., the point will be plotted with error
  283.        bars at (x+dx, y+dy) and (x-dx, y-dy).
  284.  
  285.        For the xy, xydx, xydy, xydxdx, xydydy, xydxdy  data  file
  286.        formats,  sets  are  separated  by  a line containing non-
  287.        numeric characters, that are neither comment lines  (lines
  288.  
  289.                             April 1992                          5
  290.  
  291. ACE/gr(1)                                               ACE/gr(1)
  292.  
  293.        with  a '#' in column 1) nor parameter lines (lines begin-
  294.        ning with an '@').  Data files can have imbedded  comments
  295.        by  placing a '#' in the first column of the comment line.
  296.        Plot parameters can be set by placing a '@' in  the  first
  297.        column  of  the line followed immediately by the parameter
  298.        name and setting as described in the format for  parameter
  299.        files.  Comment lines and parameter lines can occur at any
  300.        place in the data file, and are not used to indicate  data
  301.        set  separators. I recommend a single '&' on a line to use
  302.        as a data set separator.
  303.  
  304.        Block data file format.
  305.  
  306.            Block data files are composed of equal length columns.
  307.        For example:
  308.  
  309.          1 2 3
  310.          4 5 6
  311.          7 8 9
  312.  
  313.        is  a block data file consisting of 3 columns. Each row is
  314.        assumed to have the same number of entries.
  315.  
  316.        Hot keys:
  317.               When the mouse is on the canvas (where the graph is
  318.               drawn),  there are some shortcuts that can be taken
  319.               to bring up several popups or perform certain oper-
  320.               ations. They are:
  321.  
  322.                 ^A - autoscale plot
  323.                 ^B  -  draw a box (using the current settings for
  324.               boxes)
  325.                 ^C - bring up the transformations popup
  326.                 ^D - delete an object (string, line, or box)
  327.                 ^E - bring up the edit points popup
  328.                 ^F - bring up the files popup
  329.                 ^G - bring up the define world/view popup
  330.                 ^L - locate the legend
  331.                 ^N - move an object (string, line, or box)
  332.                 ^P - draw a line (using the current settings  for
  333.               lines)
  334.                 ^R - bring up the files popup
  335.                 ^S - setops popup
  336.                 ^T - tics popup
  337.                 ^V - set the viewport with the mouse
  338.                 ^W  -  write a string (using the current settings
  339.               for strings)
  340.                 ^X - exit ACE/gr
  341.                 ^Z - enable zoom
  342.  
  343. NOTE:
  344.  
  345.                             April 1992                          6
  346.  
  347. ACE/gr(1)                                               ACE/gr(1)
  348.  
  349. EXAMPLES
  350.        The following examples use xmgr, xvgr will provide similar
  351.        results.
  352.  
  353.        o    Read  a  single  data  file,  autoscale axes, and use
  354.        default settings:
  355.  
  356.        unix% xmgr test.dat
  357.  
  358.        o   Read a single data file and use plot parameters previ-
  359.        ously saved in the file "test.par":
  360.  
  361.        unix% xmgr test.dat -param test.par
  362.  
  363.        or
  364.  
  365.        unix% xmgr test.dat -p test.par
  366.  
  367.        o    Read  a  data file and use plot parameters previously
  368.        saved in the file "test.par", read  the  output  resulting
  369.        from the execution of the program "myprog test.dat":
  370.  
  371.        unix%  xmgr  test.dat  -pipe test.par -source pipe "myprog
  372.        test.dat"
  373.  
  374.        o   Read data from a pipe (the '-source pipe' as the  last
  375.        command line parameter tells xmgr to read from STDIN), use
  376.        parameter file "test2.par", use device 7  to  use  as  the
  377.        hardcopy  device,  and ( -h ) don"t run interactive - just
  378.        print and quit.
  379.  
  380.        unix% awk "{print $4, $3}" mydata.dat  |  xmgr  -device  2
  381.        -param test2.par -source stdin
  382.  
  383.        o    Read data from a pipe (in this case a program running
  384.        on a hypercube), use parameter file "test2.par". The  data
  385.        will be X1, Y1, Y2, ..., Yn, (from the -nxy). Override the
  386.        settings  in  the  parameter  file  for  the  Y-axis   and
  387.        autoscale  (the  -autoscale), set the type of plot to lin-
  388.        ear-log (the -log y).
  389.  
  390.        unix%  xmgr  -param  test2.par  -nxy  -source  pipe   "rsh
  391.        ipsc2.oacis.org gdata" -autoscale y -log y
  392.  
  393. AUTHOR
  394.        Paul      Turner,      Oregon      Graduate     Institute.
  395.        pturner@amb4.ccalmr.ogi.edu.
  396.  
  397. BUGS
  398.        There is no way to abort a plot.
  399.  
  400.                             April 1992                          7
  401.  
  402.